home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / xstat.lha / XStat.doc < prev    next >
Text File  |  1992-09-04  |  16KB  |  515 lines
  1. XStat V1.10 Documentation
  2. =========================
  3.  
  4. IMPORT StdDisclaimer; (* in short: use it at your own risk *)
  5. XStat was carefully tested, but there's certainly plenty of room for bugs.
  6.  
  7. XStat V1.10 is Freeware, non-commercial distribution is o.k. as long as
  8. the following conditions are met:
  9.  
  10.   * Source, executable and documentation must be distributed together
  11.     (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
  12.     and these files must be intact (you're not allowed to make changes).
  13.  
  14.   * Disk librarians: you may charge no more than the current price
  15.     of a single AmigaLibDisk from Fred Fish (Germany: no more than
  16.     8 DM / disk)
  17.  
  18.  
  19.  
  20. XStat requires AmigaOS V37 or later (that's 2.04 or later).
  21.  
  22.  
  23.  
  24. Purpose
  25. =======
  26. XStat extracts statistic information from the Xferstat file created
  27. by Andrew "Charly" Kopp's UUCiCo V1.15c (or later). The most important
  28. information XStat offers to you is the phone cost for a certain number
  29. of connects.
  30.  
  31.  
  32.  
  33. Installation
  34. ============
  35. Copy the executable "XStat" to a dircetory in your "Path", preferably UUBIN:
  36.  
  37. There's only one more file that needs to be installed; it's called
  38. "XStat.data", and should be copied to your UULIB: directory.
  39.  
  40. You'll have to edit XStat.data to complete the installation.
  41.  
  42.  
  43.  
  44. XStat.data
  45. ==========
  46. XStat.data contains the phone cost on a "per host" basis, in the following
  47. format:
  48.  
  49. XStat.data file header:
  50. -----------------------
  51. H XSTAT DATA
  52.  
  53. This header must be the first line of XStat.data
  54.  
  55. XStat.data comment line:
  56. ------------------------
  57.  
  58. # any comments you wish to add to XStat.data
  59.  
  60. You may add comment lines anywhere in your XStat.data file, except before
  61. the file header.
  62.  
  63. XStat.data currency sign info:
  64. ------------------------------
  65. S <currency sign>
  66.  
  67. Tells XStat the currency sign for your country. This line must come before
  68. the first "N"-line. There can be only one "S"-line in your XStat.data file.
  69.  
  70. Examples:
  71.  
  72. # currency sign for the U.S.A.
  73. S $
  74.  
  75. # currency sign for Germany
  76. S DM
  77.  
  78. XStat.data host name info:
  79. --------------------------
  80. N <host name> <host name> ...
  81.  
  82. Starts a new connection cost data record. Must be followed by at least
  83. one "C"-line. <host name> should be the name of a host you're directly
  84. connected to, without any path or domain information.
  85.  
  86. Examples:
  87.  
  88. # my own newsfeed
  89. N imart
  90.  
  91. # my alternate newsfeed
  92. N cbmger
  93.  
  94. Since XStat V1.10, you can use the extended N-line syntax that allows
  95. you to specify multiple host names in a single N-line. All those hosts
  96. will have the same cost information.
  97.  
  98. Example:
  99.  
  100. # several hosts that have the same cost info's
  101. N cbmger brewak forge
  102.  
  103.  
  104.  
  105. XStat.data connection time/cost info:
  106. -------------------------------------
  107. C <start time> <duration> <price>
  108.  
  109. Tells XStat that between <start time> and <start time of next C-line>
  110. a connection will cost <price> per <duration>. "C"-lines must follow
  111. a "N"-line. <duration> must be in seconds, <price> in the currency of
  112. your choice.
  113.  
  114. The first "C"-line must be for "SU-00:00:00"!
  115. (see exception at LOCAL/IGNORE below)
  116.  
  117. Example:
  118. N imart
  119. C SU-00:00:00 120 0.23
  120. C MO-08:00:00  60 0.23
  121. C MO-18:00:00 120 0.23
  122.  
  123. From Sunday 0:00:00 to Monday 7:59:59, a connection between my
  124. site and my newsfeed "imart" will cost 0.23DM/120sec.
  125.  
  126. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
  127. and my newsfeed "imart" will cost 0.23DM/60sec.
  128.  
  129. With this short example, the connection cost for the rest of the
  130. week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
  131.  
  132. Since Version 1.09 there's another possible C-line syntax... you
  133. can also use "C IGNORE" to tell XStat to ignore all connections from
  134. and to that particular host, or you can use "C LOCAL" to specify a
  135. local connection without connection costs (only the in/out bytes
  136. will be counted in this case). If you use "LOCAL" or "IGNORE", you
  137. may NOT use the normal C-line syntax for that host.
  138. "LOCAL" and "IGNORE" are mutually exclusive.
  139.  
  140.  
  141. Example:
  142. N imart
  143. C IGNORE
  144.  
  145. will cause all connects from/to imart to be ignored.
  146.  
  147.  
  148. Example:
  149. N imart
  150. C LOCAL
  151.  
  152. will cause all connects from/to imart to be counted with cost=0.
  153.  
  154.  
  155.  
  156. Full length example for XStat.data:
  157. -----------------------------------
  158.  
  159. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  160. H XSTAT DATA
  161. #==============================================================================
  162. # XStat connection cost data file
  163. #==============================================================================
  164. #
  165. #------------------------------------------------------------------------------
  166. # currency sign for Germany; S must come before first N
  167. #------------------------------------------------------------------------------
  168. S DM
  169. #
  170. #------------------------------------------------------------------------------
  171. # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
  172. #------------------------------------------------------------------------------
  173. N imart
  174. C SU-00:00:00 120 0.23
  175. C MO-08:00:00  60 0.23
  176. C MO-18:00:00 120 0.23
  177. C TU-08:00:00  60 0.23
  178. C TU-18:00:00 120 0.23
  179. C WE-08:00:00  60 0.23
  180. C WE-18:00:00 120 0.23
  181. C TH-08:00:00  60 0.23
  182. C TH-18:00:00 120 0.23
  183. C FR-08:00:00  60 0.23
  184. C FR-18:00:00 120 0.23
  185. #
  186. #------------------------------------------------------------------------------
  187. # cbmger, brewak, forge:
  188. # connection cost is 0.23/21sec (0.23/42sec night & weekend)
  189. #------------------------------------------------------------------------------
  190. N cbmger brewak forge
  191. C SU-00:00:00  42 0.23
  192. C MO-08:00:00  21 0.23
  193. C MO-18:00:00  42 0.23
  194. C TU-08:00:00  21 0.23
  195. C TU-18:00:00  42 0.23
  196. C WE-08:00:00  21 0.23
  197. C WE-18:00:00  42 0.23
  198. C TH-08:00:00  21 0.23
  199. C TH-18:00:00  42 0.23
  200. C FR-08:00:00  21 0.23
  201. C FR-18:00:00  42 0.23
  202. #
  203. #------------------------------------------------------------------------------
  204. # demo1, this is a local (e.g. null-modem) connection
  205. #------------------------------------------------------------------------------
  206. N demo1
  207. C LOCAL
  208. #
  209. #------------------------------------------------------------------------------
  210. # demo2, connects will be ignored
  211. #------------------------------------------------------------------------------
  212. N demo2
  213. C IGNORE
  214. #
  215. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  216.  
  217.  
  218.  
  219. Usage
  220. =====
  221. XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
  222.           [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
  223.           [H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR]
  224.  
  225. You may also use the environment variable "XSTATARGS" to specify
  226. parameters. This is very useful if you're using XStat from the
  227. Workbench (XStat doesn't really support Workbench, that's why
  228. there's no icon for it).
  229.  
  230. ?
  231. -
  232. Displays a help message.
  233.  
  234. DATA name
  235. ---------
  236. Tells XStat to read its connection cost data from file <name>.
  237. <name> defaults to "UULIB:XStat.data".
  238.  
  239. FILE name
  240. ---------
  241. Tells XStat to extract the statistic information from file <name>.
  242. <name> defaults to "UUSPOOL:XferStat".
  243.  
  244. V | VERBOSE
  245. -----------
  246. Enables the "verbose" mode. When on, XStat displays short statistics
  247. for every connect found in the Xferstat file. Defaults to "off".
  248. Specify VERBOSE to turn verbose mode on.
  249.  
  250. FD | FROMDATE date
  251. ------------------
  252. Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
  253. You may use any valid AmigaDOS date string, including things like
  254. "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
  255. you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
  256. is [ought to be] currently available to registered developers only) you'll have
  257. to use your locale date specifications, for example "HEUTE" instead of "TODAY"
  258. if you're using the german locale.
  259.  
  260. TD | TODATE date
  261. ----------------
  262. Tells XStat to ignore connects after <date>. <date> defaults to current
  263. date/time. You may use any valid AmigaDOS date string, including things
  264. like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
  265. XStat will add a time string of "23:59:59" internally, you may not do this
  266. yourself.
  267.  
  268. M | MONTH shortdate
  269. -------------------
  270. Tells XStat to ignore FD and TD, and to compute the statistics for the
  271. specified month instead. The month must be given in the format "MMM-YY",
  272. without specifying the day. Example: "MONTH JUN-92" will compute the stats
  273. for June 92. MONTH is inactive as default.
  274.  
  275. NI | NOINCOM
  276. ------------
  277. Tells XStat to suppress evaluation of incoming calls; defaults to off.
  278. Specify "NI" to suppress evaluation of incoming calls. Meaning of this
  279. switch was inverted before version 1.04.
  280.  
  281. NO | NOOUTGO
  282. ------------
  283. Tells XStat to suppress evaluation of outgoing calls; defaults to off.
  284. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
  285. switch was inverted before version 1.04.
  286.  
  287. Q | QUIET
  288. ---------
  289. Tells XStat to suppress non-fatal error messages; defaults to off.
  290. Specify QUIET to suppress non-fatal errors.
  291.  
  292. This is very handy for getting rid of those "(ignoring this one)" messages
  293. for failed connects.
  294.  
  295. H | HOSTNAME
  296. ------------
  297. Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
  298. Starting with V1.06, if <name> contains any valid AmigaDos pattern,
  299. XStat will display subtotals for each host that matches these patterns.
  300.  
  301. Patterns are not case sensitive.
  302.  
  303. Example: XStat hostname (a|x)#?
  304.          will evaluate calls to all hosts that start with an "a" or "x",
  305.          and will display sub-totals for each of those hosts.
  306.  
  307. SE | STDERR
  308. -----------
  309. Tells XStat to send all error messages to StdErr instead of StdOut.
  310. Then you can redirect the statistic output to a file using ">File",
  311. without redirecting the error messages to that file as well.
  312. Redirection defaults to off; specify STDERR to enable redirecting
  313. error messages to StdErr. StdErr is always the console window
  314. XStat was started from. The STDERR option was tested with the
  315. standard AmigaShell only. It *should* work with other shells, too.
  316.  
  317.  
  318.  
  319. XStat's output
  320. ==============
  321.  
  322. Example:
  323.  
  324. > XStat 1.10
  325. > ⌐ Copyright 1992 by Jⁿrgen Weinelt
  326. >
  327. > Connection statistics for outgoing calls to host "cbmger":
  328. >
  329. > connects              14          (0 of them were local)
  330. > online time          366 sec      (      27 sec/connect)
  331. > units                 16 units    (   1.143 units/connect)
  332. > cost                3.68 DM       (   0.263 DM/connect)
  333. >
  334. > brutto read        81977 bytes    (    5856 bytes/connect)
  335. > brutto send        30380 bytes    (    2170 bytes/connect)
  336. > netto read         47451 bytes    (    3390 bytes/connect)
  337. > netto send         19489 bytes    (    1393 bytes/connect)
  338. >
  339. > av. brutto speed     306 cps      (     697 cps peak)
  340. > av. netto speed      182 cps      (     550 cps peak)
  341. > av. brutto cost   34.344 DM/MB
  342. > av. netto cost    57.645 DM/MB
  343. >
  344. >
  345. > Connection statistics for outgoing calls to host "imart":
  346. >
  347. > connects              61          (0 of them were local)
  348. > online time        12800 sec      (     210 sec/connect)
  349. > units                143 units    (   2.344 units/connect)
  350. > cost               32.89 DM       (   0.539 DM/connect)
  351. >
  352. > brutto read     11068422 bytes    (  181450 bytes/connect)
  353. > brutto send      1260468 bytes    (   20664 bytes/connect)
  354. > netto read      10120721 bytes    (  165914 bytes/connect)
  355. > netto send        175650 bytes    (    2880 bytes/connect)
  356. >
  357. > av. brutto speed     963 cps      (    1218 cps peak)
  358. > av. netto speed      804 cps      (     969 cps peak)
  359. > av. brutto cost    2.797 DM/MB
  360. > av. netto cost     3.349 DM/MB
  361. >
  362. >
  363. > Connection statistics for incoming calls:
  364. > -----------------------------------------
  365. >
  366. > no connects recorded.
  367. >
  368. >
  369. > Connection statistics for outgoing calls:
  370. > -----------------------------------------
  371. >
  372. > connects              75          (0 of them were local)
  373. > ignored connects       0
  374. > online time        13166 sec      (     176 sec/connect)
  375. > units                159 units    (   2.120 units/connect)
  376. > cost               36.57 DM       (   0.488 DM/connect)
  377. >
  378. > brutto read     11150399 bytes    (  148672 bytes/connect)
  379. > brutto send      1290848 bytes    (   17212 bytes/connect)
  380. > netto read      10168172 bytes    (  135576 bytes/connect)
  381. > netto send        195139 bytes    (    2602 bytes/connect)
  382. >
  383. > av. brutto speed     944 cps      (    1218 cps peak)
  384. > av. netto speed      787 cps      (     969 cps peak)
  385. > av. brutto cost    3.082 DM/MB
  386. > av. netto cost     3.700 DM/MB
  387.  
  388. connects
  389. --------
  390. Number of connects, and number of local (=free) connects
  391. (XStat.data "C LOCAL").
  392.  
  393. ignored connects
  394. ----------------
  395. Number of connects that were IGNOREd (-> XStat.data "C IGNORE").
  396.  
  397. online time
  398. -----------
  399. Total online time, and average online time per connect.
  400.  
  401. units
  402. -----
  403. Phone units consumed, and average phone units consumed per connect.
  404.  
  405. Note: in Germany, a "phone unit" is an indivisible time quantum
  406. (sounds like quantum physics :-). This means even if your connect
  407. is shorter than that, the phone company still charges for the entire
  408. time quantum. Example: unit duration is 60 seconds, connect time was
  409. 97 seconds, phone company charges two units (120 seconds).
  410.  
  411. You can influence the unit duration by editing the XStat.data file;
  412. the <duration> in the "C"-lines tells XStat the unit duration.
  413.  
  414. cost
  415. ----
  416. Total cost, and average cost per connect.
  417.  
  418. brutto read
  419. -----------
  420. Total bytes read (including protocol information), and average (per connect).
  421.  
  422. brutto send
  423. -----------
  424. Total bytes sent (including protocol information), and average (per connect).
  425.  
  426. netto read
  427. ----------
  428. Total bytes read (excluding protocol information), and average (per connect).
  429.  
  430. netto send
  431. ----------
  432. Total bytes sent (excluding protocol information), and average (per connect).
  433.  
  434. av. brutto speed
  435. ----------------
  436. Average transmission speed, including protocol overhead, and speed of
  437. fastest connect.
  438.  
  439. av. netto speed
  440. ---------------
  441. Average transmission speed, excluding protocol overhead, and speed of
  442. fastest connect.
  443.  
  444. av. brutto cost
  445. ---------------
  446. Average cost per MByte, including protocol overhead.
  447.  
  448. av. netto cost
  449. --------------
  450. Average cost per MByte, excluding protocol overhead.
  451.  
  452.  
  453.  
  454. History
  455. =======
  456. V1.10   added multiple name feature to XStat.data N-Line syntax
  457.         fixed a small bug in the NI/NO feature
  458. V1.09   added LOCAL and IGNORE to XStat.data C-line syntax
  459. V1.08   added STDERR option, replaced "°" with "av."
  460. V1.07   list of connection statistics was not sorted correctly. Fixed.
  461. V1.06   extended "hostname" to include pattern matching and "per host" feature
  462. V1.05   added "per host" statistics
  463. V1.04   fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
  464. V1.03   added monthly statistics.
  465. V1.02   added peak brutto/netto cps rating.
  466. V1.01   XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
  467. V1.00   initial release.
  468.  
  469. V0.9x   several test/beta versions, limited circulation
  470.  
  471.  
  472.  
  473. Known problems/bugs
  474. ===================
  475. None so far...
  476.  
  477. Well, actually, there's one problem I can't do anything about... the
  478. online time is not very accurate. That's because the connection start
  479. time seems to state the time the modem says "CONNECT", not the real
  480. start time of the (phone line) connection.
  481.  
  482.  
  483.  
  484. You can contact me through the Usenet:
  485.  
  486.    swb.de!imart!hcast!jow
  487. or
  488.    uunet.uu.net!cbmvax!cbmehq!cbmger!imart!hcast!jow
  489.  
  490. (Sorry, still no domain address)
  491.  
  492. Or through the snail mail:
  493.  
  494.    Jⁿrgen Weinelt
  495.    Zur Kanzel 1
  496.    D-8783 Hammelburg
  497.    Germany
  498.  
  499. You might also try posting to comp.sys.amiga.programmer or alt.sys.amiga.uucp,
  500. I'll probably read those newsgroups.
  501.  
  502.  
  503.  
  504. Thanks
  505. ======
  506. The following people contributed suggestions and bug reports:
  507.  
  508.   Christian Balzer
  509.   Kai Bolay
  510.   Michael-Wolfgang Hohmann
  511.   Andrew Kopp
  512.   Henning Schmiedehausen
  513.  
  514. Thank you all.
  515.